Crate glium

source ·
Expand description

Easy-to-use, high-level, OpenGL3+ wrapper.

Glium is based on glutin - a cross-platform crate for building an OpenGL window and handling application events.

Glium provides a Display which extends the glutin::WindowedContext with a high-level, safe API.

Initialization

The initialisation of a glium display occurs in several steps.

extern crate glium;

fn main() {
    // 1. The **winit::EventsLoop** for handling events.
    let mut events_loop = glium::glutin::event_loop::EventLoop::new();
    // 2. Parameters for building the Window.
    let wb = glium::glutin::window::WindowBuilder::new()
        .with_inner_size(glium::glutin::dpi::LogicalSize::new(1024.0, 768.0))
        .with_title("Hello world");
    // 3. Parameters for building the OpenGL context.
    let cb = glium::glutin::ContextBuilder::new();
    // 4. Build the Display with the given window and OpenGL context parameters and register the
    //    window with the events_loop.
    let display = glium::Display::new(wb, cb, &events_loop).unwrap();
}

The display object is the most important object of this library and is used when you build buffers, textures, etc. and when you draw.

You can clone it and pass it around. However it doesn’t implement the Send and Sync traits, meaning that you can’t pass it to another thread.

The display has ownership of both the window and context, and also provides some methods related to domains such as events handling.

Overview

OpenGL is similar to a drawing software: you draw something, then draw over it, then over it again, etc. until you are satisfied of the result.

Once you have a display, you can call let mut frame = display.draw(); to start drawing. This frame object implements the Surface trait and provides some functions such as clear_color, but also allows you to draw with the rendering pipeline.

In order to draw something, you will need to pass:

  • A source of vertices (see the vertex module)
  • A source of indices (see the index module)
  • A program that contains the shader that the GPU will execute (see the program module)
  • A list of uniforms for the program (see the uniforms module)
  • Draw parameters to customize the drawing process (see the draw_parameters module)

Once you have finished drawing, you can call frame.finish() to swap buffers and present the result to the user.

OpenGL equivalents in glium

  • Bind points: Glium automatically binds and unbinds buffers, textures, etc. in an optimized way.
  • Buffers: Buffers are strongly typed and can be used through vertex::VertexBuffer, index::IndexBuffer or uniforms::UniformBuffer.
  • Debug output: If you compile in debug mode, glium registers a debug output callback and panics if an OpenGL error happens.
  • Framebuffer Objects: FBOs are automatically managed by glium and are stored in the Context object. You can specify the attachments that you wish with the framebuffer module.
  • Instancing: Instancing is done either by passing a vertex::EmptyInstanceAttributes marker or one or several references to vertex buffers wrapped inside a PerInstance struct. See the vertex module for more infos.
  • Memory barriers: Calling glMemoryBarrier is automatically handled by glium, however you still need to call memoryBarrier() in your GLSL code in some situations.
  • Programs: See the program module.
  • Query objects: The corresponding structs are in the draw_parameters module. They are passed as draw parameters.
  • Renderbuffer: See the framebuffer module.
  • Render to texture: If you just want to draw on a texture, you can call texture.as_surface(). For more advanced options, see the framebuffer module.
  • Samplers: Samplers are automatically managed by glium and are stored in the Context object. You can specify how a texture should be sampled by using a Sampler dummy object in the uniforms module.
  • Shaders: You can’t manually create individual shaders. Instead you must create whole programs at once.
  • Textures: Textures are strongly typed and are found in the texture module.
  • Uniform blocks: If your program uses uniform blocks, you must pass a reference to a uniform buffer for the name of the block when drawing.
  • Vertex array objects: VAOs are automatically managed by glium if the backend supports them.

Re-exports

Modules

  • backend
    The backend module allows one to link between glium and the OpenGL context..
  • buffer
    A buffer is a memory location accessible to the video card.
  • debug
  • draw_parameters
    Describes miscellaneous parameters to be used when drawing.
  • field
    Field utils
  • framebuffer
    Framebuffers allow you to customize the color, depth and stencil buffers you will draw on.
  • index
    In order to draw, you need to provide a way for the video card to know how to link primitives together.
  • memory_object
    Contains everything related to external API memory objects.
  • pixel_bufferDeprecated
    Moved to the texture module.
  • program
    Items related to creating an OpenGL program.
  • semaphore
    Contains everything related to external API semaphores.
  • texture
    A texture is an image loaded in video memory, which can be sampled in your shaders.
  • uniforms
    A uniform is a global variable in your program. In order to draw something, you will need to give glium the values of all your uniforms. Objects that implement the Uniform trait are here to do that.
  • vertex
    Contains everything related to vertex sources.

Macros

  • assert_no_gl_error
    Calls the assert_no_error method on a glium::Display instance with file and line number information.
  • field
    A macro to create a Field.
  • implement_buffer_content
    Implements the glium::buffer::Content trait for the given type.
  • implement_uniform_block
    Implements the glium::uniforms::UniformBlock trait for the given type.
  • implement_vertex
    Implements the glium::vertex::Vertex trait for the given type.
  • program
    Builds a program depending on the GLSL version supported by the backend.
  • uniform
    Returns an implementation-defined type which implements the Uniform trait.

Structs

  • BlitMask
    Mask specifying, which kinds of buffers to copy when blitting between two frame buffers.
  • BlitTarget
    Area of a surface in pixels. Similar to a Rect except that dimensions can be negative.
  • Frame
    Implementation of Surface, targeting the default framebuffer.
  • IncompatibleOpenGl
    Returned during Context creation if the OpenGL implementation is too old.
  • LinearSyncFence
    Prototype for a SyncFence.
  • Rect
    Area of a surface in pixels.
  • SyncFence
    Provides a way to wait for a server-side operation to be finished.
  • Version
    Describes a version.

Enums

  • Api
    Describes an OpenGL-related API.
  • DrawError
    Error that can happen while drawing.
  • Handle
    Handle to a shader or a program.
  • Profile
    Describes the OpenGL context profile.
  • RawUniformValue
    A raw value of a uniform. “Raw” means that it’s passed directly with glUniform. Textures for example are just passed as integers.
  • ReadError
    Error that can happen while reading.
  • SwapBuffersError
    Error that can happen when swapping buffers.
  • UuidError
    Describes an error preventing the retrieval of the uuid.

Traits

  • CapabilitiesSource
    Trait for objects that describe the capabilities of an OpenGL backend.
  • GlObject
    Trait for objects that are OpenGL objects.
  • Surface
    Object that can be drawn upon.

Functions

  • get_supported_glsl_version
    Given an API version, this function returns the GLSL version that the implementation is required to support.